/**
 * Copyright (c) 2014, Oracle America, Inc.
 * All rights reserved.
 * <p>
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 * <p>
 * 允许以源代码和二进制形式进行再分发和使用，无论是否经过修改，均须满足以下条件：
 * <p>
 *  * Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * <p>
 *  * Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * <p>
 *  * Neither the name of Oracle nor the names of its contributors may be used
 *    to endorse or promote products derived from this software without
 *    specific prior written permission.
 * <p>
 * 1. 源代码的再分发必须保留上述版权声明、此条件列表和以下免责声明。
 * 2. 二进制形式的再分发必须在随附的文档和/或其他材料中包含上述版权声明、此条件列表和以下免责声明。
 * 3. 未经事先书面许可，不得使用 Oracle 的名称或其贡献者的名称来支持或推广源自本软件的产品。
 * <p>
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION)
 * <p>
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * <p>
 * 本软件由版权持有人和贡献者“按现状”提供，且不作任何明示或暗示的保证，包括但不限于对适销性和特定用途适用性的暗示保证。
 * 在任何情况下，版权持有人或贡献者均不对因使用本软件而导致的任何直接、间接、附带、特殊、惩罚性或后果性损害承担责任
 * （包括但不限于替代商品或服务的采购、使用损失、数据丢失或利润损失，或业务中断），
 * <p>
 * 无论是在何种责任理论下，无论是合同责任、严格责任或侵权责任（包括过失或其他原因），即使已被告知可能发生此类损害。
 */
package com.example.performance.jmh.official;

import org.openjdk.jmh.annotations.Benchmark;
import org.openjdk.jmh.runner.Runner;
import org.openjdk.jmh.runner.RunnerException;
import org.openjdk.jmh.runner.options.Options;
import org.openjdk.jmh.runner.options.OptionsBuilder;

@SuppressWarnings("java:S101")
public class JMHSample_01_HelloWorld {

    /**
     * This is our first benchmark method.
     * <p>
     * JMH works as follows: users annotate the methods with @Benchmark,
     * and then JMH produces the generated code to run this particular benchmark as reliably as possible.
     * In general one might think about @Benchmark methods as the benchmark "payload", the things we want to measure.
     * The surrounding infrastructure is provided by the harness itself.
     * <p>
     * Read the Javadoc for @Benchmark annotation for complete semantics and restrictions.
     * At this point we only note that the methods names are non-essential,
     * and it only matters that the methods are marked with @Benchmark.
     * You can have multiple benchmark methods within the same class.
     * <p>
     * Note: if the benchmark method never finishes, then JMH run never finishes as well.
     * If you throw an exception from the method body, the JMH run ends abruptly for this benchmark
     * and JMH will run the next benchmark down the list.
     * <p>
     * Although this benchmark measures "nothing" it is good showcase for the
     * overheads the infrastructure bear on the code you measure in the method.
     * There are no magical infrastructures which incur no overhead,
     * and it is important to know what are the infra overheads you are dealing with.
     * You might find this thought unfolded in future examples by having the
     * "baseline" measurements to compare against.
     */
    @Benchmark
    public void wellHelloThere() {
        // this method was intentionally left blank.
    }

    /**
     * ============================== HOW TO RUN THIS TEST: ====================================
     * <p>
     * You are expected to see the run with large number of iterations, and very large throughput numbers.
     * You can see that as the estimate of the harness overheads per method call.
     * In most of our measurements, it is down to several cycles per call.
     * <p>
     * a) Via command-line:
     *    $ mvn clean install
     *    $ java -jar target/benchmarks.jar JMHSample_01_HelloWorld
     * <p>
     * JMH generates self-contained JARs, bundling JMH together with it.
     * The runtime options for the JMH are available with "-h":
     *    $ java -jar target/benchmarks.jar -h
     * <p>
     * b) Via the Java API:
     *    (see the JMH homepage for possible caveats when running from IDE:
     *      <a href="http://openjdk.java.net/projects/code-tools/jmh/">...</a>)
     */
    public static void main(String[] args) throws RunnerException {
        Options opt = new OptionsBuilder()
                .include(JMHSample_01_HelloWorld.class.getSimpleName())
                .forks(1)
                .build();

        new Runner(opt).run();
    }

}